FM deployment

This section provides an overview of how to deploy a single FM or multiple FMs on an HSM device. The ProtectToolkit-C Administrator can deploy FMs by using the Functionality Module Manager (ctfm). The Embedded Linux Development Kit (ELDK) package must also be installed on the client system.

Deploy a single FM

To use an FM you must sign the FM binary and load the signed .fm file onto the HSM.

To deploy a single FM

1. Compile the FM.

   1. Navigate to the directory where the FM binary components are stored. By default, this directory is /opt/safenet/protecttoolkit7/fmsdk/samples/<fmname>/fm.

   2. Set FMDIR as an environment variable with the following value:

      FMDIR=/opt/safenet/protecttoolkit7/fmsdk

   3. Use the make command to build the FM binary.

      The make process creates a new subdirectory (obj-ppc). Your FM binary is located in obj-ppc in the following format and named <filename>.bin.

2. Sign the compiled FM.

   1. Navigate to the directory containing the FM binary image.

   2. Use mkfm to sign the FM and generate a .fm file.

      mkfm -kSLOTID=<HSMslotID>/<PrivateKeyLabel> -f <fmBinary> -0 <fmFile>.fm

      Note

      The output file name must be a .fm file.

      The slot must have a token name implemented or the mkfm command will fail.

      The minimum key size for FM signing is 2048 bits.

   3. Use ctcert to import the certificate into the Admin slot

      ctcert i -f<certificate_file> -l<certificate_label> [-s<admin_slot>]

   4. Use ctcert to make the certificate trusted.

      ctcert t -l<certificate_label> [-s<admin_slot>]

3. Load the FM onto the HSM.

   1. Navigate to the directory where the .fm file is stored and load the .fm onto the HSM.

      ctfm i -a<device> -l<certLabel> -f<.fmFile>

   2. Confirm that the FM was loaded successfully.

      ctfm q -a<device>

Deploy Multiple FMs

To deploy multiple FMs you must sign the FM binary and load the signed .fm file onto the HSM. Note the following:

• Each FM must have a unique FMID.

• The FMID must be compiled into the FM as part of the FM image.

• You must use the FMID when calling the FM.

Configuring a unique FMID

Before you compile your FM, you must assign a unique FMID to it by defining the MY_FM_NUMBER macro in the hdr.c file. Subsequently, you compile the FM using make, sign the FM binary, and load the .fm file onto the HSM.

To configure a unique FMID

1. Open the FM hdr.c file in a text editor. Add the following line to define the MY_FM_NUMBER value.

   #define MY_FM_NUMBER <FMID>
   

   Note

   The MY_FM_NUMBER value must be input as a hexadecimal value from 0x100 to 0xffff (values below 0x100 are unavailable). Subsequent calls to the FM must be directed towards the FMID value. For example, an hdr.c MY_FM_NUMBER value of 0x100 results in an FMID of 256. The ctfm and ctconf utilities display FMIDs in hex mode.

Calling FMID

On an HSM device with multiple loaded FMs you must direct calls towards the unique FMID. Adhere to the following:

• You must use the FMID value to register any dispatch using FMSW_RegisterDispatch.

• You must use the FMID value for any host application such as MD_SendReceive.

• You must use the correct FMID when registering a custom command handler in the FM startup.

Example FM that has been assigned an FMID of 0x300

Configuration of the FM hdr.c file.

    #!text
    #define MY_FM_NUMBER 0x300

    DEFINE_FM_HEADER(MY_FM_NUMBER,
    FM_VERSION,
    FM_SER_NO,
    FM_MANUFACTURER,
    FM_NAME);

Using the FMID value in the host application MD_SendReceive.

    #!text
    rv = MD_SendReceive( adapter,
    originatorID,
    MY_FM_NUMBER,
    request,
    RESERVED,
    reply,
    &recvLen,
    &appState);

Delete an FM from the HSM

Run the following command to delete an FM from the HSM:

ctfm d -i<fmID> [-a<device>|-A]